Python Integration

In eCognition it is possible to write applications using Python. The algorithm 'execute python script' allows the processing of Python files (*.py ) or the insertion of Python scripts directly into the algorithm.

Manage Python Environments

Select Tools > Manage Python Environments to clone existing, add new, edit, or remove Python environments.

 

• Clone... - creates a copy of the selected environment and opens the Clone Environment dialog where you can set the environment's name and path.

The default environment eCognition-env is installed on activation of the check box Python Support during setup (see chapter Prerequisite above), containing the default Python libraries included in eCognition.

• Activate - activates the selected environment (active *). The active environment is used to run any Python functionality executed in eCognition.
  To change the active environment, select the environment and click Activate. (If you change the active environment, a restart of eCognition is only necessary, if the python interpreter was already in use.)
  

• Add New... - creates a new, empty environment. If a Requirements file is specified, packages from this file are installed. Note that Numpy, pandas, and shapely packages are always required and need to be installed before an environment can be activated in eCognition. The requirements file stores the required python packages and optionally their versions. (see https://pip.pypa.io/en/stable/reference/requirements-file-format/)

   

  In the Clone/Add Environment dialog you can set the environment's Name and path. By default, a new or cloned environment is created in the folder C:\ProgramData\eCognition\Python\Envs. To create the environment in a different folder, click the Folder browse button.

   

  
  

• Remove - deletes the selected environment. Note that the default environment eCognition-env and the currently active environment can not be removed.

• List Packages... - Select an environment and click this button to obtain a list of all Python packages and their versions installed for the selected environment in the output log.

• Command prompt ... - Opens the command line interpreter application to enter and execute commands, install packages or obtain information for the selected environment (not the active, but the selected environment). The command prompt opens based on the selected environment, for example:
  (env1) C:\Program Files\Trimble\eCognition Developer 10.3\bin>.

• Clear Log - Deletes all log entries of the output log.

Alternatively, you can open the context menu by right-click on an environment to choose among the functionality Clone, Activate, Remove, List Packages and Command prompt.

 

Input to and output from python

The following input and output is supported:

• Raster layers

• Variables - double or string (variables that are returned to eCognition must be of floating or integer type)

• Regions

• Arrays - double or string (output array elements have to be of the same type, e.g. only double or only string)

• Point clouds (multiple point clouds can be passed to the script, but cannot iterate over multiple point clouds at the same time)

• Vectors (attribute elements of the same column cannot have different data type, vector geometries must be of one type within one vector object)

Debugging python code in eCognition Developer

Using an external debugger for python scripts the following requirements have to be fulfilled:

• supported for python files (and not for inline scripts)

• only Windows OS is supported

• Integrated development environment (IDE) that supports debugpy remote debugger is required, for example: Visual Studio Code (VS Code) with Python extension or Visual Studio

In this documentation, we provide an example how to attach a debugger using Visual Studio Code (VS Code).

Integrated development environment (IDE) setup

First, you need to install the Python extension in VS Code.

• Go to Extensions and search for Python extensions in the marketplace.

• Install the extension.

• After installing the extension, you need to create a launch.json file.

In the launch.json file specify the host and the port:

• 'host' is localhost

• 'port' is 5678

Any open port can be used here, but then the same number must be used in the script function
ecog.wait_for_debugger(port=5678)

Please find the sample content of launch.json below (copy & paste enabled):

{

    // Use IntelliSense to learn about possible attributes.

    // Hover to view descriptions of existing attributes.

    // More information: https://go.microsoft.com/fwlink/?linkid=830387

    "version": "0.2.0",

    "configurations": [

        {

            "name": "Python: Remote Attach",

            "type": "python",

            "request": "attach",

            "connect": {

                "host": "localhost",

                "port": 5678

            }

           

           

        }

    ]

}

IntelliSense

eCognitions python module supports IntelliSense features. See the example below how to enable it in VS Code.

• Go to the main menu View > Command Palette...

• Start searching for Python: Select interpreter.

Enter the correct interpreter path from your eCognition installation. This path should lead to the python.exe file of the current active eCognition python environment.

• The default environment with the preinstalled packages is saved in (default location of python.exe):

  C:\Program Files\Trimble\eCognition Developer 10.3\bin\Python\eCognition-env\Scripts

• If you are using custom python environments, they are, by default, saved in:

  C:\ProgramData\eCognition\Python\Envs

 

Now your IntelliSense should work when typing 'ecog.' in VS Code IDE.

Debugging

Start debugging

To start a debugging session uncomment the function call below (or if you are writing the script from the scratch, add the following line to your python script):

The port number must match the port number used in launch.json file.

ecog.wait_for_debugger(port=5678)

• Open the same python file that you run in eCognition Developer and set a breakpoint.

• In eCognition, execute the algorithm 'python script' with the python file in it. The method wait_for_debugger will block the code execution and wait for a debugger to connect.

Now you can switch back to VS Code and start a Debugging session (F5).

 

Stop debugging

After you are finished developing and debugging your python code, comment out the following line in the python script:

#ecog.wait_for_debugger(port=5678)

Execute algorithm 'python script'

Save the script and disconnect (Shift+F5) in VS Code. You can now execute the algorithm 'python script' in eCognition Developer.

To ensure transferability of your rule set it is recommended to use the 'inline script' mode of the algorithm 'python script' for the final rule set.

Script Examples

These script examples can be used in the algorithm 'python script'.

Example 1 - Layer Normalization

This example normalizes all raster layers by dividing each value by 255. For each layer that is passed a new normalized layer is created.

import ecognition as ecog

def image_normalization(input_dict):

layers = input_dict["raster"]

  for name, raster in layers.items():
     new_name = "Normalized " + name
     new_layer_data = raster.read_data() / 255.0
     new_raster = ecog.Raster.create_raster(new_name, new_layer_data)
    new_raster.close()

Example 2 - Variable Sum

The following example sums all process variables that are passed and creates a new variable “var_sum” that will contain the sum.

import ecognition as ecog

def sum_variables(input_dict):
  variables = input_dict["variable"]
  res = 0

  for var in variables.values():
    if not isinstance(var, str):
      res += var

  ecog.set_variable("var_sum", res)

Example 3 - Variable Concatenation

The following example concatenates all variables that are passed and creates a new variable “var_concat_string” that will contain the concatenated string.

 

import ecognition as ecog

def concat_string(input_dict):
  variables = input_dict["variable"]
  res = ""

  for var in variables.values():
    if isinstance(var, str):
      res += var

  ecog.set_variable("var_concat_string", res)

Example 4 - Double Array Elements

This example doubles the elements in all arrays that are passed.

 

import ecognition as ecog

def double_arr_values(input_dict):
  arr = input_dict["array"]

  for name, arr in arr.items():
    new_name = "doubled " + name
    new_arr = [2 * val for val in arr]
    ecog.set_array(new_name, new_arr)

Example 5 - Create Raster Layer

The following example creates a new raster layer. The size of the raster layer will be equal to the size of the region “reg_image_size”, while the values will be equal to the value of the variable “var_image_value”.

 

import ecognition as ecog
import numpy as np

def create_image(input_dict):
  image_val = input_dict["variable"]["var_image_value"]
  region = input_dict["region"]["reg_image_size"]

  sz_x = int(region[1][0])
  sz_y = int(region[1][1])

  img = np.full((sz_y, sz_x), image_val, dtype=np.float32)
  raster = ecog.Raster.create_raster("python_image", np.dtype(np.float32))
  raster.write_data(img)
  raster.close()

Example 6 - Create Point Vector Layer

This example creates a new vector layer called “point_vector_layer”. The layer will contain 3 points, each with a single vector attribute “point_id”.

 

import ecognition as ecog
import pandas as pd
from shapely.geometry import Point

def create_vector(input_dict):
  vector_data = pd.DataFrame(data={
    "point_id": [0, 1, 2],
    "geometry": [Point(17.2, 13), Point(18, 20.5), Point(15.5, 17)],
  })

  ecog.Vector.create_vector("point_vector_layer", "Point", vector_data)

Example 7 - Split Point Cloud Layer

This script creates two new point cloud layers from one point cloud layer “Layer 1”. The new point cloud layers are called “class_0” and “class_5”. The layer “class_0” will contain only the points that have a classification equal to 0, while the layer “class_5” will have points that have a classification equal to 5.

 

import ecognition as ecog
import numpy as np

def split_pc(input_dict):
  pc = input_dict["point_cloud"]["Layer 1"]

  cls_0 = ecog.PointCloud.create_point_cloud("class_0")
  cls_5 = ecog.PointCloud.create_point_cloud("class_5")

  for chunk in pc.get_chunk_iterator(points_in_chunk=10000):
    cls_0_indices = np.where(chunk.classification == 0)[0]
    cls_5_indices = np.where(chunk.classification == 5)[0]

    cls_0.add_points(
      chunk.x[cls_0_indices],
      chunk.y[cls_0_indices],
      chunk.z[cls_0_indices],
      chunk.intensity[cls_0_indices],
      chunk.red[cls_0_indices],
      chunk.green[cls_0_indices],
      chunk.blue[cls_0_indices],
      np.full(len(cls_0_indices), 0, dtype=np.uint8),
    )

    cls_5.add_points(
      chunk.x[cls_5_indices],
      chunk.y[cls_5_indices],
      chunk.z[cls_5_indices],
      chunk.intensity[cls_5_indices],
      chunk.red[cls_5_indices],
      chunk.green[cls_5_indices],
      chunk.blue[cls_5_indices],
      np.full(len(cls_5_indices), 5, dtype=np.uint8),
    )

  cls_0.close()
  cls_5.close()

 

For more information see also:

Installation Guide > Windows > Python Installation - installation and setup

Reference Book > Algorithms and Processes > Miscellaneous > Python Script - description algorithm and its parameters

Reference Book > Algorithms and Processes > Miscellaneous > Python API Reference - reference for each class, properties, and methods